.TH std::chrono::duration 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::chrono::duration \- std::chrono::duration

.SH Synopsis
   Defined in header <chrono>
   template<

       class Rep,                    \fI(since C++11)\fP
       class Period = std::ratio<1>

   > class duration;

   Class template std::chrono::duration represents a time interval.

   It consists of a count of ticks of type Rep and a tick period, where the tick period
   is a compile-time rational fraction representing the time in seconds from one tick
   to the next.

   The only data stored in a duration is a tick count of type Rep. If Rep is floating
   point, then the duration can represent fractions of ticks. Period is included as
   part of the duration's type, and is only used when converting between different
   durations.

.SH Member types

   Member type Definition
   rep         Rep, an arithmetic type representing the number of ticks
               Period
               \fI(until C++17)\fP
   period      typename Period::type
               \fI(since C++17)\fP, a std::ratio representing the tick period (i.e. the
               number of second's fractions per tick)

.SH Member functions

   constructor     constructs new duration
                   \fI(public member function)\fP
   operator=       assigns the contents
                   \fI(public member function)\fP
   count           returns the count of ticks
                   \fI(public member function)\fP
   zero            returns the special duration value zero
   \fB[static]\fP        \fI(public static member function)\fP
   min             returns the special duration value min
   \fB[static]\fP        \fI(public static member function)\fP
   max             returns the special duration value max
   \fB[static]\fP        \fI(public static member function)\fP
   operator+       implements unary + and unary -
   operator-       \fI(public member function)\fP
   operator++
   operator++(int) increments or decrements the tick count
   operator--      \fI(public member function)\fP
   operator--(int)
   operator+=
   operator-=      implements compound assignment between two durations
   operator*=      \fI(public member function)\fP
   operator/=
   operator%=

.SH Non-member functions

   operator+
   operator-                    implements arithmetic operations with durations as
   operator*                    arguments
   operator/                    \fI(function template)\fP
   operator%
   \fI(C++11)\fP
   operator==
   operator!=
   operator<
   operator<=
   operator>
   operator>=
   operator<=>                  compares two durations
   \fI(C++11)\fP                      \fI(function template)\fP
   \fI(C++11)\fP(removed in C++20)
   \fI(C++11)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   (C++20)
   duration_cast                converts a duration to another, with a different tick
   \fI(C++11)\fP                      interval
                                \fI(function template)\fP
   floor(std::chrono::duration) converts a duration to another, rounding down
   \fI(C++17)\fP                      \fI(function template)\fP
   ceil(std::chrono::duration)  converts a duration to another, rounding up
   \fI(C++17)\fP                      \fI(function template)\fP
   round(std::chrono::duration) converts a duration to another, rounding to nearest,
   \fI(C++17)\fP                      ties to even
                                \fI(function template)\fP
   abs(std::chrono::duration)   obtains the absolute value of the duration
   \fI(C++17)\fP                      \fI(function template)\fP
   operator<<                   performs stream output on a duration
   (C++20)                      \fI(function template)\fP
   from_stream                  parses a duration from a stream according to the
   (C++20)                      provided format
                                \fI(function template)\fP

.SH Helper types

   A type /* intXX */ used in the table below means a signed integer type of at least
   XX bits.

   Type                              Definition
   std::chrono::nanoseconds          std::chrono::duration</* int64 */, std::nano>
   std::chrono::microseconds         std::chrono::duration</* int55 */, std::micro>
   std::chrono::milliseconds         std::chrono::duration</* int45 */, std::milli>
   std::chrono::seconds              std::chrono::duration</* int35 */>
   std::chrono::minutes              std::chrono::duration</* int29 */, std::ratio<60>>
   std::chrono::hours                std::chrono::duration</* int23 */,
                                     std::ratio<3600>>
   std::chrono::days \fI(since C++20)\fP   std::chrono::duration</* int25 */,
                                     std::ratio<86400>>
   std::chrono::weeks \fI(since C++20)\fP  std::chrono::duration</* int22 */,
                                     std::ratio<604800>>
   std::chrono::months \fI(since C++20)\fP std::chrono::duration</* int20 */,
                                     std::ratio<2629746>>
   std::chrono::years \fI(since C++20)\fP  std::chrono::duration</* int17 */,
                                     std::ratio<31556952>>

   Note: each of the predefined duration types up to hours covers a range of at least
   ±292 years.

   Each of the predefined duration types days, weeks, months and years
   covers a range of at least ±40000 years. years is equal to 365.2425    \fI(since C++20)\fP
   days (the average length of a Gregorian year). months is equal to
   30.436875 days (exactly 1/12 of years).

.SH Helper classes

   std::common_type<std::chrono::duration> specializes the std::common_type trait
   \fI(C++11)\fP                                 \fI(class template specialization)\fP
   treat_as_floating_point                 indicates that a duration is convertible to
   \fI(C++11)\fP                                 duration with different tick period
                                           \fI(class template)\fP
   duration_values                         constructs zero, min, and max values of a
   \fI(C++11)\fP                                 tick count of given type
                                           \fI(class template)\fP
   std::formatter<std::chrono::duration>   formatting support for duration
   (C++20)                                 \fI(class template specialization)\fP
   std::hash<std::chrono::duration>        hash support for std::chrono::duration
   (C++26)                                 \fI(class template specialization)\fP

.SH Literals

   Defined in inline namespace std::literals::chrono_literals
   operator""h   a std::chrono::duration literal representing hours
   \fI(C++14)\fP       \fI(function)\fP
   operator""min a std::chrono::duration literal representing minutes
   \fI(C++14)\fP       \fI(function)\fP
   operator""s   a std::chrono::duration literal representing seconds
   \fI(C++14)\fP       \fI(function)\fP
   operator""ms  a std::chrono::duration literal representing milliseconds
   \fI(C++14)\fP       \fI(function)\fP
   operator""us  a std::chrono::duration literal representing microseconds
   \fI(C++14)\fP       \fI(function)\fP
   operator""ns  a std::chrono::duration literal representing nanoseconds
   \fI(C++14)\fP       \fI(function)\fP

   Note: the literal suffixes d and y do not refer to days and years but  \fI(since C++20)\fP
   to day and year, respectively.

.SH Notes

   The actual time interval (in seconds) that is held by a duration object d is roughly
   equal to d.count() * D::period::num / D::period::den, where D is of type
   chrono::duration<> and d is an object of such type.

    Feature-test macro    Value    Std                 Feature
   __cpp_lib_chrono_udls 201304L \fI(C++14)\fP User-defined literals for time types

.SH Example

   This example shows how to define several custom duration types and convert between
   types:


// Run this code

 #include <chrono>
 #include <iostream>

 using namespace std::chrono_literals;

 template<typename T1, typename T2>
 using mul = std::ratio_multiply<T1, T2>;

 int main()
 {
     using microfortnights = std::chrono::duration<float,
         mul<mul<std::ratio<2>, std::chrono::weeks::period>, std::micro>>;
     using nanocenturies = std::chrono::duration<float,
         mul<mul<std::hecto, std::chrono::years::period>, std::nano>>;
     using fps_24 = std::chrono::duration<double, std::ratio<1, 24>>;

     std::cout << "1 second is:\\n";

     // integer scale conversion with no precision loss: no cast
     std::cout << std::chrono::milliseconds(1s).count() << " milliseconds\\n"
               << std::chrono::microseconds(1s).count() << " microseconds\\n"
               << std::chrono::nanoseconds(1s).count() << " nanoseconds\\n";

     // integer scale conversion with precision loss: requires a cast
     std::cout << std::chrono::duration_cast<std::chrono::minutes>(1s).count()
               << " minutes\\n";

     // floating-point scale conversion: no cast
     std::cout << microfortnights(1s).count() << " microfortnights\\n"
               << nanocenturies(1s).count() << " nanocenturies\\n"
               << fps_24(1s).count() << " frames at 24fps\\n";
 }

.SH Output:

 1 second is:
 1000 milliseconds
 1000000 microseconds
 1000000000 nanoseconds
 0 minutes
 0.82672 microfortnights
 0.316887 nanocenturies
 24 frames at 24fps
